home *** CD-ROM | disk | FTP | other *** search
/ TOS Silver 2000 / TOS Silver 2000.iso / Anwendun / a2html / a2html-0.81 / docs / readme.txt < prev   
Encoding:
Text File  |  1999-08-28  |  15.6 KB  |  423 lines
  1. Århus 28. August 1999.
  2.  
  3.  
  4. This program will convert a simple 8bit ascii textfile into a htmlfile. 
  5. The result is a 'preformatted' 7 bit htmlfile. The textfile may use a 8-
  6. bit Atari charset or 8 bit iso-8859-1 charset.
  7.  
  8. A2html is written by Tommy Andersen <tommya@post3.tele.dk>. It is PD, 
  9. anybody (that's you) may use it or even sell it. Distribution is allowed 
  10. and you may put the package on your website, in shareware programs and 
  11. other obscure locations.
  12.  
  13. Feel free to email bugreports, patches or idea's. Thanx to many people for 
  14. feed backs. My mailbox has no limits, so don't be afraid to send very 
  15. large emails.
  16.  
  17.                  -----------------------------------
  18.  
  19. Installation:
  20. -------------
  21.  
  22. Unpack the zipfile. A2html can be used immediately, but to use the package 
  23. better, follow one or more of these steps:
  24.  
  25. Atari desktop users would drag a2html.ttp to the desktop (textfiles can 
  26. later be dropped on that icon).
  27.  
  28. Mufpel users could copy a2html.ttp to c:\bin, and a2html.0 to the cat1 
  29. pages in C:\gemini2\man\cat1 - and rename a2html.0 to a2html.1.
  30.  
  31. MiNT users may do the same as the desktop users, but are likely to copy 
  32. a2html.ttp to /usr/local/bin, rename a2html.ttp to a2html, "chmod +x 
  33. a2html", and copy a2html.1 to /usr/local/man/man1. To use a2html (without 
  34. .ttp filetype) on the desktop, they may have to "ln -s a2html a2html.ttp" 
  35. and drag a2html.ttp to the desktop.
  36.  
  37. Linux people may copy a2html.1 to /usr/local/man/man1, compile a2html and 
  38. copy a2html to /usr/local/bin.
  39.  
  40.  
  41. Files
  42. -----
  43.  
  44. a2html-0.81/                  (Top directory - 0.81 is the version)
  45.   a2html.ttp                  A2html (Atari TTP program)
  46.   docs/
  47.     readme.txt                You're reading it
  48.     charset.txt               Some charset tables (Atari)
  49.     a2html.1                  Manpage for unix
  50.     a2html.0                  Ascii preformatted manpage
  51.     a2htmlrc                  Example of an initialization file
  52.   source/
  53.     a2html.c                  The C-source of a2html
  54.     makefile.lcc              Makefile for Lattice C-Compiler (Atari)
  55.     makefile.gcc              Makefile for GCC (Atari)
  56.     makefile.lnx              Makefile for GCC (Linux)
  57.     changelog                 List of changes in the sources.
  58.  
  59.  
  60. Normal use:
  61. -----------
  62.  
  63. You can start a2html from your favourite shell or directly from the 
  64. desktop.
  65.  
  66. From desktop:
  67.  
  68.     Doubleclick a2html.ttp and enter a filename (complete path!) and a 
  69.     htmlfile will be created in the same directory on your disk.
  70.  
  71.     Or drag 'n drop some textfiles on a2html and multiple textfiles can be 
  72.     converted at once. Filenames with space(s) can not be converted in 
  73.     this way with a stu<mumble mumble> simple desktop, but smart desktops 
  74.     can do it.
  75.  
  76.     The dropped textfiles will be converted into htmlfiles, with the same 
  77.     name as the source, but with a html filetype. Existing htmlfiles with 
  78.     same name will be deleted and overwritten with no warnings.
  79.  
  80.  
  81. From a shell, you may enter the name of the program and some filenames.
  82. Examples:
  83.  
  84.     $a2html my.txt
  85.      will make "my.html".
  86.  
  87.     $a2html one.txt two.txt three.txt
  88.      will make "one.html" "two.html" "three.html"
  89.  
  90.     $a2html one.txt -o result.html
  91.      will make "result.html" from one.txt
  92.  
  93.     $a2html one.txt -o a.html two.txt -o b.html
  94.      will make "a.html" from one.txt and "b.html" from two.txt.
  95.  
  96.     $a2html *.txt
  97.      will convert all txt files in current directory. Your shell (not 
  98.      a2html) will expand *.txt to real filenames.
  99.  
  100.     $ls | a2html
  101.      will produce a html listning on your screen.
  102.  
  103.     $ls | a2html -o list.html
  104.      will send it all down to "list.html"
  105.  
  106.     $a2html one.txt -
  107.      will send the result from the textfile one.txt to your screen
  108.  
  109.     $a2html one.txt - | program
  110.      will pipe the result from the textfile one.txt to your program
  111.  
  112.     $ls | a2html - | program
  113.      will make a2html act as a filter. You may use some switches to omit 
  114.      the predefined headers.
  115.  
  116.     $man gcc | col -bx | a2html -o gcc.html
  117.      will make a html man-page for your GCC compiler.
  118.  
  119.     $find ./ -name '*.txt' -exec a2html {} \;
  120.      will make a recursive search and convert all textfiles to html.
  121.  
  122.  
  123. Table 1 in the file "charset.txt" lists all charaters that will be 
  124. converted. Atari users using the standard system font or GDOS, are using 
  125. the Atari charset. Table 2 displays 8 bit Atari characters and the iso-
  126. 8859-1 name.
  127.  
  128. First, every char from the textfile are converted from the Atari charset 
  129. (8-bit) to the iso-8859-1 (8-bit) charset. Secondly, it will be converted 
  130. to a html (7-bit) syntax.
  131.  
  132. If you are using an iso-8859-1 font as the system font look in the next 
  133. section.
  134.  
  135. Characters not found in the iso-8859-1 charset will be replaced with a 
  136. space.
  137.  
  138. The Atari charset is default if running a2html on an Atari. If a2html was 
  139. compiled on Linux, the iso-8859-1 charset is default.
  140.  
  141. Special use:
  142. ------------
  143. If you created your document with an iso-8859-1 charset/font, enter:
  144.  
  145.  $a2html -iso-8859-1 mytext.txt   on the commandline
  146.  
  147. The '-iso-8859-1' option tells a2html, that the file already uses a 8 bit 
  148. iso-8859-1 charset. All characters can and will be converted into 7 bit 
  149. html syntax.
  150.  
  151. Strange things
  152. --------------
  153.  
  154. Syntax is:
  155.  
  156. a2html -option textfile -o htmlfile
  157.  
  158. The textfile is the inputfile, the htmlfile is the outputfile. Not 
  159. recognized options will be used as a textfile. Read "-p, -pause" as
  160. "-p" or "-pause".
  161.  
  162. Options:
  163.  
  164. -p, -pause
  165.          The program waits for a keypress (Return) before it terminates.
  166.  
  167. -q, -quiet
  168.          The program will not display errors on screen.
  169.  
  170. -dumpargs
  171.          Dumps all arguments on stderr. Could be used to validate the ARGV 
  172.          function.
  173.  
  174. --help   Lists all valid options to a2html. If a pause is required, use -p 
  175.          before --help.
  176.  
  177. --version 
  178.          Prints version of a2html.
  179.  
  180. -crlf    Now.. Default is to use a single LF to finish a line. Use this 
  181.          switch if you want a CR too. It does not matter how the lines 
  182.          are finished in the textfile, they will always be LF or CRLF 
  183.          terminated.
  184.  
  185. -iso, -iso-8859-1
  186.          Textfile uses an iso-8859-1 charset.
  187.  
  188. -atari   Textfile uses an Atari charset.
  189.  
  190. -notags  The htmlfile does not have <html>, <head>, doctype tags. You can 
  191.          paste or merge the file into an existing htmlfile. Links will 
  192.          still be created.
  193.  
  194. -nopre   Omit <pre> </pre> tags. The resulting htmlcode may look ugly in 
  195.          your browser.
  196.  
  197. -nobr    -nopre (see above) will terminate all lines with <br>. Use -nobr 
  198.          to omit <br>.
  199.  
  200. -nolinks Don't make links from for url's in textfile.
  201.  
  202. -nomail  Don't make mailto's from anything that looks like an emailaddress.
  203.  
  204. -nodoctype
  205.          Don't output the W3C document type definition (3.2) in the 
  206.          beginning of the htmlfile.
  207.  
  208. -footer <string>
  209.          Outputs the string after the last </pre> and just before </body>. 
  210.          String will not be charset parsed, and links will not be created. 
  211.          The string may have linefeeds and tags. Using quotes in the 
  212.          string and newlines (from a shell) could be a problem, however 
  213.          not from a calling (GEM) program.
  214.  
  215. -o <htmlfile>, -out <htmlfile>
  216.          Write output to htmlfile.
  217.          With no "-o htmlfile" option, a2html will look at the name of the 
  218.          previous textfile and change it to a html filetype.
  219.  
  220. -, -stdout
  221.          Force output (the htmlcode) to standard output.
  222.  
  223. -title <string>
  224.          Changes the html document title for the current htmlfile. More 
  225.          titles are allowed in one session, but a title applies only to 
  226.          the current textfile. Use "" when a2html is started from a shell. 
  227.          The title will be charset parsed, so you can use 8 bit characters.
  228.  
  229. -emailsource
  230.          a2html reads the textfile as an email and will only display Date, 
  231.          From, Reply-To, To, Cc and Subject fields. However, a2html will 
  232.          not convert quoted-printable nor mime-encoded emails. These will 
  233.          be displayed as they look (in the bodytext). When this option is 
  234.          invoked, a2html will change default charset to iso-8859-1. The 
  235.          complete header is hidden in comments, just select "view source" 
  236.          in your browser.
  237.  
  238. -separator <string>
  239.          Outputs the string between the header and body text. String must 
  240.          be valid htmlcode and will not be charset parsed.
  241.          Example: -separator "<hr>"
  242.  
  243. -bodybgcolor <color>
  244.          Changes the default background color white to <color>.
  245.  
  246. -bodytext <color>
  247.          Changes the default text color black to <color>.
  248.  
  249. -bodylink <color>
  250.          Changes the default link color blue to <color>.
  251.  
  252. No textfile
  253.          a2html will read input from standard input.
  254.  
  255.  
  256. Using a2htmlrc
  257. --------------
  258.  
  259. a2html will look for a2htmlrc (and .a2htmlrc) in current working directory 
  260. and in your home directory. The home directory is found with the HOME 
  261. environment variable. If an a2htmlrc file is found, it will be used before 
  262. the options on the commandline. Only one a2htmlrc file is read.
  263.  
  264. You can find an example of an a2htmlrc file in the docs directory, with 
  265. all a2htmlrc options listed.
  266.  
  267. When a2html is started from the desktop (drag'drop), it will properly not 
  268. find the a2htmlrc file! Most desktop shells will set the current working 
  269. directory (cwd) to the directory with a2html.ttp, and not to where the 
  270. textfiles are. However, some desktops will let you "install" a2html, and 
  271. you may get the choice of setting the directory to the right one.
  272.  
  273.  
  274. Compiling a2html
  275. ----------------
  276.  
  277. a2html can be compiled with GCC (MiNT/MagiC or Linux) and Lattice C.
  278.  
  279. Lattice C: Enter "make -f makefile.lcc"
  280.            Note that I never use the projectmanager, but always gnu make.
  281.            You will also need mintbind.h, so a2html can go into the MiNT 
  282.            domain (long filenames on MiNT and MagiC) with Pdomain().
  283.  
  284. GCC 2.8.1: You can compile a2html with this commandline from tsch or your 
  285.            favorite shell (commandline wrapped):
  286.              gcc -O2 -fomit-frame-pointer -m68000 -mshort -DATARI
  287.              a2html.c -o a2html.ttp
  288.            or simply:
  289.              make -f makefile.gcc
  290.  
  291. Linux:     Just enter "make -f makefile.lnx"
  292.  
  293. Other:     Well, try compile it. Take care of the stdin/stdout 
  294.            translation, it must be done in binary mode (LF not converted 
  295.            to LF+CR). You should use a ANSI-style compiler with a ANSI-
  296.            type C-library.
  297.  
  298.  
  299. Final notes:
  300. ------------
  301.  
  302. 0.1 -> 0.2 Doctype changed from HTML 3.2 to HTML 2.0. W3C forgot the 
  303.            " in the HTML 3.2 DTD, and the result was a huge 
  304.            errorlist from "A Kinder, Gentler HTML Validator", see
  305.            "http://ugweb.cs.ualberta.ca/~gerald/validate/". No 
  306.            problems when a HTML 2.0 doctype is used.
  307.  
  308. 0.2 -> 0.3 Runs on Linux 68k. Type 'make -f makefile.lnx' and copy 
  309.            a2html to /usr/local/bin
  310.            If no inputfile then a2html will read from stdin. You can 
  311.            now pipe text in and pipe result into another program.
  312.  
  313. 0.3 -> 0.4 Major rewrite. Links like http://home3.inet.tele.dk/tommya will 
  314.            be tagged with <a href="....">link</a>. Some checks are made, 
  315.            and if your links just doesn't appear as a link, the link could 
  316.            be broken. These url types are being checked: ftp, http, file, 
  317.            news, wais, nntp, imap, https, telnet, mailto and gopher. If 
  318.            you don't like a2html to make these links, just enter
  319.            -nolinks on the commandline.
  320.  
  321.            Well, coded a email checker into a2html too. If a2html meets 
  322.            something like user@host, it will make a mailto link. And if 
  323.            you don't like that either, enter -nomail on the commandline.
  324.  
  325.            Possible to specify a outputfile, if you want a2html to use 
  326.            that, you must enter an inputfile.
  327.  
  328.            If you enter an inputfile, but (no) outputfile, a2html will 
  329.            write output to a2html.html.
  330.  
  331.            If a2html couldn't make the html file, it will return 1.
  332.  
  333. 0.4 -> 0.5 Bug found and fixed. Look at the sourcecode for more 
  334.            informations on that.
  335.  
  336.            a2html will try to save the output in a file with the same name 
  337.            as the inputfile, but with the extension (filetype) changed to 
  338.            html. It will never save anything to a2html.html anymore. That 
  339.            is, the input file isn't called a2html ;-)
  340.  
  341.            If you enter an illegal switch on the commandline, it would be 
  342.            taken as a filename. It still does that, but since that 
  343.            filename (switch) doesn't exist, it won't delete your inputfile 
  344.            (it would be taken as an outputfile).
  345.  
  346.            A new switch -nopre removes <pre> </pre> from the outputfile. 
  347.            However, the html file could now be interpreted as one big 
  348.            line, so <br> are inserted at the very end at each line. 
  349.            Doublespaces, spaces at the beginning of a line etc will vanish 
  350.            in your browser (html rule). It looks a little bit ugly at the 
  351.            moment. If you don't like the <br>, enter -nobr on the 
  352.            commandline.
  353.  
  354.            Url's like <url:http://home3.inet.tele.dk/tommya/> are now 
  355.            recognized too. See RFC1738 for more information.
  356.  
  357. 0.5 -> 0.6 Url's like (http://host/path) will not include the ( ) in the 
  358.            link (highlighted part). Same story with (tommya@post3.tele.dk).
  359.            <wrong:http//host/> are recognized as an invalid url. Prospero 
  360.            url type included.
  361.  
  362. 0.6 -> 0.7 Another bug found. Second time this happens :( Only when -iso 
  363.            mode was used, and a 8-bit characters was converted. Fixed.
  364.            End tags in proper order.
  365.            " changed to ". If you are validating a html 3.2 
  366.            document with a2html generated body text (copy and pasted to 
  367.            your document), the " would produce some errors.
  368.            W3C Validator Services: http://validator.w3.org/.
  369.  
  370.            Well, compiled MiNTLib pl48 for the good old Lattice Compiler, 
  371.            but the Lattice binary is only 5K smaller than the GCC binary, 
  372.            so next versions of a2html will be compiled with GCC.
  373.  
  374.            Major changes in commandline parsing. Multiple inputfiles at 
  375.            once is possible.
  376.  
  377.            All switches are global, that is, you can not convert a -atari 
  378.            and a -iso file at the same time and get the right result.
  379.  
  380. 0.7 -> 0.8 Man-page created. Corrected the documentation.
  381.            Just added a extra check for very long words. MiNTLib pl49 is 
  382.            used now.
  383.            Bug fixed - if last argument was '-o' then a2html would crash :(
  384.            Another one fixed - could take place in very rare situations.
  385.  
  386.            New option, -title "string" will change title. Title will be 
  387.            changed for current outputfile (or inputfile). Example from 
  388.            your shell:
  389.            $a2html one.txt -title "File no. 1" two.txt -title "File no. 2"
  390.  
  391.            Title will always be parsed into 7bit html syntax.
  392.  
  393.            New options: -nodoctype, -footer "html-code"
  394.            New option: -emailsource and -separator "html-code"
  395.  
  396.            New options -bodybgcolor <color> -bodytext <color> and -
  397.            bodylink <color>.
  398.  
  399.            Html 3.2 doc header.
  400.  
  401.            Well, the sources are now under rcs control, and a new 
  402.            distribution can be made in 20 sec (some smart scripts used).
  403.            If any files are missing then blame it on my smart scripts.
  404.  
  405.            --version added, -quiet, -pause, -iso-8859-1 can also be used.
  406.  
  407.            Usage should be more friendly, and this readme text should now 
  408.            have a better consistency.
  409.  
  410.            Fixed some backrunning pointers.
  411.  
  412.            a2html will now look for an a2htmlrc file.
  413.  
  414.            Checks a2htmlrc variables for overrun. Man page updated.
  415.  
  416. 0.8 ->     No Home environment variable bug fixed (2 bombs!).
  417.  
  418. Oh... just use it and enjoy :-)
  419.  
  420. CU
  421.  
  422. Tommy Andersen
  423.